%==========================================================================
%=  This file is part of the Sound Restoration Project
%=  (c) Copyright Industrial Mathematics Institute
%=                University of South Carolina, Department of Mathematics
%=  ALL RIGHTS RESERVED
%=
%=  Author: Borislav Karaivanov
%==========================================================================

%==========================================================================
% List of the files on which this procedure depends:
%
% setLogWritingFunctHandle.m
% writeToLogFile.m
%
%==========================================================================

%==========================================================================
% The function "read2DArrayFromFile" reads a 2D array of floats from a
% specified text file.
% INPUT: "fileName" is a string specifying the name of the text file to be
% read including a full directory path.
% "writeToLogFunctHandle" is an optional function handle which writes to a
% fixed log text file if keeping a log is requested, or does nothing
% otherwise.
% OUTPUT: "read2DArr" returns the 2D array read form the file.
%==========================================================================
function read2DArr = read2DArrayFromFile(fileName, writeToLogFunctHandle)

if (nargin < 2)
    writeToLogFunctHandle = @(x) '';
end

% Set the output to be used in case of illegitimate file.
read2DArr = [];

% If the output file does not exist, then there is no signal. Otherwise,
% explore the existing file.
if (exist(fileName, 'file') ~= 2)
    writeToLogFunctHandle(['Warning in read2DArrayFromFile: The file ' fileName ' does not exist.']);
    return;
end

% Open the file for reading.
fid = fopen(fileName, 'rt');
if (fid == -1)
    writeToLogFunctHandle(['Warning in read2DArrayFromFile: Unable to open the file ' fileName ' for reading.']);
    return;
end

% Try to read in the desired patterns from the first two lines.
currLine = fgetl(fid);
numRows = sscanf(currLine, 'number of rows: %d\n');
currLine = fgetl(fid);
numCols = sscanf(currLine, 'number of columns: %d\n');

if ( (~isempty(numRows))||(~isempty(numCols)) )
    
    % If the first two lines do match the desired patterns, then try to
    % read in the specified number of floats from the subsequent lines.
    [read2DArr, numRead] = fscanf(fid, '%f\n', inf);
    
    % If the number of read floats is the same as the one specified on the
    % first two lines, then the file appears legitimate.
    if (numRead == (numRows*numCols))
        % Reshape the read floats to form a rectangular array assuming they
        % were written column after column.
        read2DArr = reshape(read2DArr, numRows, numCols);
    else
        % Set the output to be used in case of illegitimate file.
        read2DArr = [];
    end
end

% Close the file.
fclose(fid);

if isempty(read2DArr)
    writeToLogFunctHandle('Warning in read2DArrayFromFile: The read array is empty.');
end

return;
% end of the function "read2DArrayFromFile"
